Interactively moving panes to other windows / sessions (tmux)

I found out something interesting I'm gonna share with you today.

For the uninitiated, you can execute commands in tmux with <prefix>: (by default <C-b>:).

It's about moving panes in tmux. Now, let's get the terminology straight (it's kind of strange):

• A pane contains a single running program

• A window contains one or more panes laid out in some way. The window is represented by its name (and index) in the status bar.

• A session has one or more windows. They are listed in the statusbar.

You might already know how to move a pane to, say, another window. You can do it with the join-pane command.

There are pretty much 2 convenient ways to use join-pane:

• use it to send the current pane to another window: join-pane -t <window_index>

• use it to take a panel from another window and put it here join-pane -s <window_index>. this takes the first pane from the specified window.

But the description above is misleading. The command is actually way more powerful. Here's the rundown of how join-pane can be really used:

join-pane -t <destination> -s <source>

where either -t or -s with their appropriate arguments can be left out. If it is left out, the argument is set to 'current pane' or 'marked pane' if you've used <prefix>m to mark some pane. I don't use that shortcut.

But what can <destination> and <source> be? We'll call them addresses.

They can be:

• A [<session>:]<window>[.<pane>] address where [] denotes optional specifiers. Examples:

  • join-pane -t 2 moves the current pane to window 2 of the current session

  • join-pane -t net-pers:2 moves the current pane to window 2 of a session called net-pers

  • join-pane -s net-pers:2.1 moves the second (because panes are 0-indexed) pane of window 2 of session net-pers below the current panel

  • join-pane -t 3.2 moves the current pane after the third pane of window 3 of the current session.

So, you can actually send a pane to another tmux session! This is super useful for multiple-monitor setups! You can even bind it to a key!

Now, you may have seen the interactive command for this in someone's .tmux.conf.

bind-key m command-prompt -p "send pane to:"  "join-pane -t '%%'"

This requires You to enter the address.

But if You really wanted to do it interactively, you can have tmux show you the session/window/pane tree and you can pick the source or destination. You even have previews. I never use the source variant, only destination.

Here are my bindings:

bind-key M choose-tree -Zw "join-pane -t '%%'"
bind-key C-m choose-tree -Zs "join-pane -t '%%'"

M opens up a tree view with windows collapsed, and lets You pick out a destination where You want to put the current pane.
C-m opens up a tree view with sessions collapsed, and lets You pick out a destination where You want to put the current pane.

You can navigate the tree view with UpArrow and DownArrow or k and j, collapsing and uncollapsing are done with RightArrow/l and LeftArrow/h respectively. The destination is selected with Return, and you can cancel the selection with q or Esc.

Try it out, it's super useful!